\chapter{Time Chess Engine Communication Protocol Specification}
\label{protocol} \label{TCECP} \label{protocol-spec}

The Time Chess Engine Communication Protocol (TCECP) is a simple
text protocol designed to facilitate communication between \TC
engines and \TC GUIs. It is inspired by the Chess Engine
Communication Protocol (CECP).

The protocol works by exchanging single line messages. The GUI
sends single line messages to the Engine. Some of these messages
require the engine to respond with a line of its own. The Engine
does not send messages to the GUI except in response to a message
from the GUI.

\section{Messages from the GUI to the Engine}

\newcommand{\rl}{\raggedleft}
\begin{tabular}{p{0.3\textwidth}p{0.7\textwidth}@{\vspace{1em}}}

\rl\verb!new!               &   Abandon any ongoing games and `make` a new game, as though the system has just been started up. Expects no reply.\\

\rl\verb!ping <NUMBER>!     &   Check the engine is connected and responding.\\

\rl\verb!<POSITION>! \tiny{(e.g. \verb!a1t0!)}  &   Request a list of moves possible for the piece at \verb!<POSITION>! (See section~\ref{pos-notation}).\\

\rl\verb!<MOVE>! \tiny{(e.g. \verb!a2t0a4t0!)}  &   Attempt to make the move \verb!<MOVE>! (See section~\ref{pos-notation}).\\

\rl\verb!getState t!        &   Get the current turn. In theory this need never be called, but a disagreement between the GUI and the Engine about what turn it is would be disastrous.\\

\rl\verb!getState <TURN>!   &   Request the state of the board at turn \verb!<TURN>!\\

\end{tabular}

\section{Messages from the Engine to the GUI}

\begin{tabular}{p{0.35\textwidth}p{0.6\textwidth}@{\vspace{1em}}}

\rl\verb!pong <NUMBER>! &   (In reply to \verb!ping <NUMBER>!) Confirm that the engine is connected and responding by \verb!pong!ing the same number you were \verb!ping!ed\\

\rl \verb!moves (<POSITION>):!\\\verb! [<LIST>]!        &   (In reply to \verb!<POSITION>!) \verb![<LIST>]! is a list of moves possible for the piece at \verb!<POSITION>!, as a valid JSON array of strings. \small{(e.g. \texttt{moves (a4t5): ["a4t5","a3t6"]})}\\

\rl Move Result         &   (In reply to \verb!<MOVE!>) Either the string \verb!Success! if the move worked, or an error message in the format \texttt{Illegal move (<REASON>): <MOVE>}. \small{(e.g. \texttt{Illegal move (Move puts you in check): a1t0a4t0})}\\

\rl\verb!<TURN>!        &   (In reply to \verb!getState t!) An integer showing the current turn number\\

\rl \verb!state (<TURN>): [LIST]!   &   (In reply to \verb!getState <TURN>!) \verb![LIST]! is a list of pieces on the board at turn \verb!<TURN>!, as a JSON array of arrays of the form \verb![<POSITION>,<COLOUR>,<TYPE>]!, each representing a piece. \small{(e.g. \verb![["c3t30","w","k"],!\verb!["e7t30","b","k"],! \verb!["e8t30","b","q"]]!)}\\

\rl \verb!futureQueue: [LIST]! &    (In reply to \verb!getState futureQueue!) \verb![LIST]! is a list of pieces in the future queue, in the same format at the board state. \small{(e.g. \verb![["a1t5", "w", "r"]]!)}

\end{tabular}

